Alpha Anywhere Tutorial Definition
Description
The .a5tut extension is used for defining an interactive tutorial.
Fields
- Name
- Property and Description
- action
Track action to follow
- name
Name of action
- where
Fully Qualified identifier of action location in the UX.
- message
HTML content to display associated with the control or subitem of a control identified by the 'where' property.
- edge
Edge of control specified by the 'where' property to display the message (left, right, top, bottom).
- exactMatch
For this step to complete, the value of the control specified by the 'where' property must match this value.
Can be an object rather than a string if the control specified for 'where' does not match the control for the action.
- skipMatch
If the value of the control specified by the 'where' property matches this value, this step is skipped.
Can be an object rather than a string if the control specified for 'where' does not match the control for the action.
- skipNotMatch
If the value of the control specified by the 'where' property does not matche this value, this step is skipped.
- validateEval
This contains an optional xbasic expression, which can contain a <dlgtitle> placeholder, which gets replaced with the string of the xdialog specified by the actions 'where' property.
The expression should return a logical .t. if the action is valid (at which point, the action script will advance to the next action).
- skipEval
This contains an optional xbasic expression, which can contain a <dlgtitle> placeholder, which gets replaced with the string of the xdialog specified by the actions 'where' property.
The expression should return a logical .t. if the action should be skipped.
- step
Identifies this as the last action in a 'step'.
- continue
Add the 'next' step to the 'page' this step is one.
- skipTo
The purpose is to skip a 'block' of commands if a skip condition is met / skips to a step identfied by a label.
- label
Name a target for a skipTo.
Actions
- Action
- Property and Description
- menuSelect
Action is a menu selection , can be top menu or context menu or submenu.
- controlChange
Action is result of user editing the value of a control.
- controlSelect
Action is result of user selecting the value of a control.
- controlClick
Action is the result of the user clicking on a control.
- controlDoubleClick
Action is the result of the user double clicking on a control.
- controlRightClick
Action is the result of the user right clicking on a control.
- controlAny
Action is *any* action on a control (this is generally used in conjuction with an 'exactMatch' where a control value might be set via selection or editing).
- viewActivate
Action is the result of the user selecting a diffent view, generally by clicking on the title section.
- include
Action is placeholder for actions in another file (where property contains relative path).
ExactMatch, SkipMatch Object
- Property
- Description
- where
Specifies the control to follow the value of.
- value
Specifies the match 'value'.
Example with SkipMatch
In this example, when the tutorial script is run from the web control panel, a message will point to the 'Web Components' entry of in the Web Control Panel Selector if the 'Web Components' page is not the active page. Then a message will show up above the 'new' button.
{
"actions": [
{
"action": "controlChange",
"name": "Web Components",
"where": "/WebControlPanel/list/Category/Web Components",
"message": "Change Web Components control.",
"skipMatch": "Web Components",
"step": 1
},
{
"action": "buttonClick",
"name": "New",
"where": "/WebControlPanel/button/New",
"message": "Click New button.",
"edge": "top",
"step": 2
},
]
}Example of tracking changes to List Content
Below is a standalone tutorial code example of a dialog that has a button that adds elements to a list, and advances to the *next* step only when the list has 7 entries.
Note that exactMatch is an object instead of a string, because the action is the button click, but the value to Test is the content of the list.
Also note that the list content is denoted by the control path (/Test/list/item) with the #List suffix.
Also note that the sample xdialog uses the {where=} keyword to specify the well known name.
dim json as c = <<%json%
{
"actions": [
{
"action": "buttonClick",
"name": "Add",
"where": "/Test/button/Add",
"message": "Click Add button.",
"step": 2,
"continue" : true ,
"exactMatch" : {
"where" : "/Test/list/item#List",
"value" : "One\nTwo\nThree\nFour\nFive\nSix\nSeven"
}
},
{
"action": "buttonClick",
"name": "Close",
"where": "/Test/button/Close",
"message": "Click Close button.",
"step": 3
}
]
}
%json%
dim uxa as WindowManager::UxAutomation
uxa.RunTutorial(json,.f.)
dim item as c
dim items as c = <<%str%
One
Two
%str%
ui_dlg_box("test",<<%dlg% {where=/Test}
[.80,20item^#items];
<Add!add><Close!close>;
%dlg%,<<%code%
if a_dlg_button = "add" then
a_dlg_button = ""
items = alltrim(items) + crlf() + str(line_count(items)+1,200,0,"XF")
end if
%code%)Example of using Xbasic expressions to Validate and Skip
If the validation or skip rules provided are not enough, there are two rules that call into xbasic that allow for arbitrarily complex validation.
The following script demonstrates a Validation rule and a Skip rule that are bound to two logical variables maintained by the example xdialog.
dim json as c = <<%json%
{
"actions": [
{
"action": "buttonClick",
"name": "Add",
"where": "/Test/button/Add",
"message": "Click Add button.",
"step": 2,
"continue" : true ,
"validateEval" : "ui_dlg_eval(<dlgtitle>,\"valid\")"
},
{
"action": "buttonClick",
"name": "Optional",
"where": "/Test/button/Optional",
"message": "Click Optional button.",
"step": 3,
"skipEval" : "ui_dlg_eval(<dlgtitle>,\".not. require_optional\")"
},
{
"action": "buttonClick",
"name": "Close",
"where": "/Test/button/Close",
"message": "Click Close button.",
"step": 4
}
]
}
%json%
dim uxa as WindowManager::UxAutomation
uxa.RunTutorial(json,.f.)
dim item as c
dim valid as l = .f.
dim require_optional as l = .f.
dim items as c = <<%str%
One
Two
%str%
ui_dlg_box("test",<<%dlg% {where=/Test}
[.80,20item^#items];
(valid!state_change) Its valid;
(require_optional!state_change) Require Optional Step;
<Add!add><Optional!optional><Close!close>;
%dlg%,<<%code%
if a_dlg_button = "add" then
a_dlg_button = ""
items = alltrim(items) + crlf() + str(line_count(items)+1,200,0,"XF")
else if a_dlg_button = "optional" then
a_dlg_button = ""
ui_msg_box("optional step","clicking on this button is optional")
else if a_dlg_button = "state_change" then
a_dlg_button = ""
end if
%code%)